
/*
 * Copyright 2002-2022 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2022原作者。
 *
 *根据Apache许可证2.0版（“许可证”）许可；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，否则软件
 *根据许可证分发是在“按原样”的基础上分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证
 *许可证下的限制。
 */

package org.springframework.context.aot;

import java.io.IOException;
import java.nio.file.Path;

import org.springframework.aot.generate.FileSystemGeneratedFiles;
import org.springframework.aot.generate.GeneratedFiles.Kind;
import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.nativex.FileNativeConfigurationWriter;
import org.springframework.lang.Nullable;
import org.springframework.util.Assert;
import org.springframework.util.FileSystemUtils;

/**
 * Abstract base class for filesystem-based ahead-of-time (AOT) processing.
 *
 * <p>Concrete implementations should override {@link #doProcess()} that kicks
 * off the optimization of the target, usually an application.
 *
 * @author Stephane Nicoll
 * @author Andy Wilkinson
 * @author Phillip Webb
 * @author Sam Brannen
 * @since 6.0
 * @param <T> the type of the processing result
 * @see FileSystemGeneratedFiles
 * @see FileNativeConfigurationWriter
 * @see org.springframework.context.aot.ContextAotProcessor
 * @see org.springframework.test.context.aot.TestAotProcessor
 */
/**
 *用于基于文件系统的提前处理（AOT）的抽象基类。
 *
 *<p>具体的实现应该覆盖启动的{@link#doProcess（）}
 *偏离目标的优化，通常是一个应用程序。
 *
 *@作者Stephane Nicoll
 *@作者Andy Wilkinson
 *@作者Phillip Webb
 *@作者Sam Brannen
 *@自6.0起
 *@param＜T＞处理结果的类型
 *@参见文件系统生成的文件
 *@参见FileNativeConfigurationWriter
 *@参见org.springframework.context.aot.ContextAotProcessor
 *@参见org.springframework.test.context.aot.TestAotProcessor
 */
public abstract class AbstractAotProcessor<T> {

	/**
	 * The name of a system property that is made available when the processor
	 * runs.
	 * @see #doProcess()
	 */
	/**
	 *处理器启动时可用的系统属性的名称
	 *跑步。
	 *@参见#doProcess（）
	 */
	private static final String AOT_PROCESSING = "spring.aot.processing";

	private final Settings settings;


	/**
	 * Create a new processor instance with the supplied {@linkplain Settings settings}.
	 * @see Settings#builder()
	 */
	/**
	 *使用提供的｛@linkplain设置｝创建一个新的处理器实例。
	 *@请参阅设置#builder（）
	 */
	protected AbstractAotProcessor(Settings settings) {
		this.settings = settings;
	}


	/**
	 * Get the {@linkplain Settings settings} for this AOT processor.
	 */
	/**
	 *获取此AOT处理器的｛@linkplain设置｝。
	 */
	protected Settings getSettings() {
		return this.settings;
	}

	/**
	 * Run AOT processing.
	 * @return the result of the processing.
	 */
	/**
	 *运行AOT处理。
	 *@返回处理结果。
	 */
	public final T process() {
		try {
			System.setProperty(AOT_PROCESSING, "true");
			return doProcess();
		}
		finally {
			System.clearProperty(AOT_PROCESSING);
		}
	}

	protected abstract T doProcess();

	/**
	 * Delete the source, resource, and class output directories.
	 */
	/**
	 *删除源、资源和类输出目录。
	 */
	protected void deleteExistingOutput() {
		deleteExistingOutput(getSettings().getSourceOutput(),
				getSettings().getResourceOutput(), getSettings().getClassOutput());
	}

	private void deleteExistingOutput(Path... paths) {
		for (Path path : paths) {
			try {
				FileSystemUtils.deleteRecursively(path);
			}
			catch (IOException ex) {
				throw new RuntimeException("Failed to delete existing output in '" + path + "'");
			}
		}
	}

	protected FileSystemGeneratedFiles createFileSystemGeneratedFiles() {
		return new FileSystemGeneratedFiles(this::getRoot);
	}

	private Path getRoot(Kind kind) {
		return switch (kind) {
			case SOURCE -> getSettings().getSourceOutput();
			case RESOURCE -> getSettings().getResourceOutput();
			case CLASS -> getSettings().getClassOutput();
		};
	}

	protected void writeHints(RuntimeHints hints) {
		FileNativeConfigurationWriter writer = new FileNativeConfigurationWriter(
				getSettings().getResourceOutput(), getSettings().getGroupId(), getSettings().getArtifactId());
		writer.write(hints);
	}

	/**
	 * Common settings for AOT processors.
	 */
	/**
	 *AOT处理器的常见设置。
	 */
	public static final class Settings {

		private final Path sourceOutput;

		private final Path resourceOutput;

		private final Path classOutput;

		private final String groupId;

		private final String artifactId;


		private Settings(Path sourceOutput, Path resourceOutput, Path classOutput, String groupId, String artifactId) {
			this.sourceOutput = sourceOutput;
			this.resourceOutput = resourceOutput;
			this.classOutput = classOutput;
			this.groupId = groupId;
			this.artifactId = artifactId;
		}


		/**
		 * Create a new {@link Builder} for {@link Settings}.
		 */
		/**
		 *为｛@link Settings｝创建一个新的｛@link Builder｝。
		 */
		public static Builder builder() {
			return new Builder();
		}


		/**
		 * Get the output directory for generated sources.
		 */
		/**
		 *获取生成的源的输出目录。
		 */
		public Path getSourceOutput() {
			return this.sourceOutput;
		}

		/**
		 * Get the output directory for generated resources.
		 */
		/**
		 *获取生成的资源的输出目录。
		 */
		public Path getResourceOutput() {
			return this.resourceOutput;
		}

		/**
		 * Get the output directory for generated classes.
		 */
		/**
		 *获取生成的类的输出目录。
		 */
		public Path getClassOutput() {
			return this.classOutput;
		}

		/**
		 * Get the group ID of the application.
		 */
		/**
		 *获取应用程序的组ID。
		 */
		public String getGroupId() {
			return this.groupId;
		}

		/**
		 * Get the artifact ID of the application.
		 */
		/**
		 *获取应用程序的工件ID。
		 */
		public String getArtifactId() {
			return this.artifactId;
		}


		/**
		 * Fluent builder API for {@link Settings}.
		 */
		/**
		 *｛@link Settings｝的Fluent生成器API。
		 */
		public static final class Builder {

			@Nullable
			private Path sourceOutput;

			@Nullable
			private Path resourceOutput;

			@Nullable
			private Path classOutput;

			@Nullable
			private String groupId;

			@Nullable
			private String artifactId;


			private Builder() {
				// internal constructor
				// 内部构造函数
			}


			/**
			 * Set the output directory for generated sources.
			 * @param sourceOutput the location of generated sources
			 * @return this builder for method chaining
			 */
			/**
			 *为生成的源设置输出目录。
			 *@param source输出生成的源的位置
			 *@返回这个用于方法链接的生成器
			 */
			public Builder sourceOutput(Path sourceOutput) {
				this.sourceOutput = sourceOutput;
				return this;
			}

			/**
			 * Set the output directory for generated resources.
			 * @param resourceOutput the location of generated resources
			 * @return this builder for method chaining
			 */
			/**
			 *为生成的资源设置输出目录。
			 *@param resource输出生成资源的位置
			 *@返回这个用于方法链接的生成器
			 */
			public Builder resourceOutput(Path resourceOutput) {
				this.resourceOutput = resourceOutput;
				return this;
			}

			/**
			 * Set the output directory for generated classes.
			 * @param classOutput the location of generated classes
			 * @return this builder for method chaining
			 */
			/**
			 *为生成的类设置输出目录。
			 *@param classOutput生成类的位置
			 *@返回这个用于方法链接的生成器
			 */
			public Builder classOutput(Path classOutput) {
				this.classOutput = classOutput;
				return this;
			}

			/**
			 * Set the group ID of the application.
			 * @param groupId the group ID of the application, used to locate
			 * {@code native-image.properties}
			 * @return this builder for method chaining
			 */
			/**
			 *设置应用程序的组ID。
			 *@param groupId应用程序的组ID，用于定位
			 *{@code native-image.财产}
			 *@返回这个用于方法链接的生成器
			 */
			public Builder groupId(String groupId) {
				this.groupId = groupId;
				return this;
			}

			/**
			 * Set the artifact ID of the application.
			 * @param artifactId the artifact ID of the application, used to locate
			 * {@code native-image.properties}
			 * @return this builder for method chaining
			 */
			/**
			 *设置应用程序的工件ID。
			 *@param artifactId应用程序的工件ID，用于定位
			 *{@code native-image.财产}
			 *@返回这个用于方法链接的生成器
			 */
			public Builder artifactId(String artifactId) {
				this.artifactId = artifactId;
				return this;
			}

			/**
			 * Build the {@link Settings} configured in this {@code Builder}.
			 */
			/**
			 *生成在此｛@code Builder｝中配置的｛@link Settings｝。
			 */
			public Settings build() {
				Assert.notNull(this.sourceOutput, "'sourceOutput' must not be null");
				Assert.notNull(this.resourceOutput, "'resourceOutput' must not be null");
				Assert.notNull(this.classOutput, "'classOutput' must not be null");
				Assert.hasText(this.groupId, "'groupId' must not be null or empty");
				Assert.hasText(this.artifactId, "'artifactId' must not be null or empty");
				return new Settings(this.sourceOutput, this.resourceOutput, this.classOutput,
						this.groupId, this.artifactId);
			}

		}

	}

}
